Skip to content

Add Learn the Basics section to ESPHome Starter Kit docs#820

Merged
bharvey88 merged 1 commit into
devfrom
esk-learn-the-basics
May 18, 2026
Merged

Add Learn the Basics section to ESPHome Starter Kit docs#820
bharvey88 merged 1 commit into
devfrom
esk-learn-the-basics

Conversation

@bharvey88
Copy link
Copy Markdown
Contributor

@bharvey88 bharvey88 commented May 18, 2026 •
edited by coderabbitai Bot
Loading

What does this implement/fix?

Adds a new Learn the Basics section to the ESPHome Starter Kit docs with three conceptual pages aimed at users who are new to ESPHome and want to understand the moving parts before diving into the step-by-step setup.

  • Explaining ESPHome clarifies the difference between ESPHome the firmware project and ESPHome Device Builder the app, explains how the device can be controlled both from any web browser (via the Web Server component) and from Home Assistant via the ESPHome integration, and weaves in the canonical open standards / local control / ESPHome ecosystem framing.
  • What is YAML? is a short primer on YAML's three core ideas (key/value, indentation, lists), covers comments, quoting strings, and common gotchas, then shows the YAML the Device Builder generates for the Onboard RGB LED so readers can recognise what they are looking at.
  • What is secrets.yaml? is a new concept page covering the purpose of secrets.yaml and !secret. It pairs with the existing Using Secrets tutorial, which has been trimmed at the top to point at the new concept page.
  • A new Learn more about ESPHome button is added directly under the ESPHome Device Builder heading on the First Steps page, giving readers a way to dive into the concept page at the moment the term first becomes hands-on relevant.

Types of changes

  • Typo / wording fix
  • Content update (correcting outdated info, adding missing steps, clarifications)
  • New page or new product section
  • Page move / rename (redirect added in mkdocs.yml)
  • Image / screenshot update
  • Nav / structure change
  • Site config or theme change
  • CI / workflows / dependencies — Does not publish

Checklist:

  • This PR targets the dev branch (not main)
  • Changes previewed locally with mkdocs serve
  • If pages were moved or renamed, redirects were added to mkdocs.yml
  • If new pages were added, nav was updated in mkdocs.yml

Summary by CodeRabbit

  • Documentation
    • Added new foundational guides covering what ESPHome is, YAML syntax concepts, and how to use secrets.yaml safely.
    • Introduced a new "Learn the Basics" navigation section to help users discover essential setup knowledge.
    • Reorganized secrets documentation by creating a dedicated reference page, reducing duplication across tutorials.

Review Change Stack

@bharvey88
Add Learn the Basics section to ESPHome Starter Kit docs
8978263 
- New Explaining ESPHome page covering ESPHome vs Device Builder, web server and Home Assistant access, and why the Starter Kit is built on ESPHome
- New What is YAML? primer with starter-kit examples and common gotchas
- New What is secrets.yaml? concept page paired with the existing Using Secrets tutorial
- Trim the Using Secrets tutorial intro to link out to the new concept page
- Add a Learn more about ESPHome button under the ESPHome Device Builder heading in First Steps
@bharvey88 bharvey88 merged commit 79d75a8 into dev May 18, 2026
1 check was pending
@bharvey88 bharvey88 deleted the esk-learn-the-basics branch May 18, 2026 18:19
@bharvey88 bharvey88 mentioned this pull request May 18, 2026
Merged
12 tasks
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 18, 2026 •
edited
Loading

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e3cc2e1-4049-4712-af42-5a2f8c7dbbff

📥 Commits

Reviewing files that changed from the base of the PR and between 6abf614 and 8978263.

📒 Files selected for processing (6)
  • docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md
  • docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md
  • docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md
  • docs/products/ESPHome-Starter-Kit/setup/first-steps.md
  • docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md
  • mkdocs.yml

Walkthrough

This PR introduces a new "Learn the Basics" documentation section for the ESPHome Starter Kit, containing three foundational concept pages: an ESPHome overview with Device Builder setup instructions, a YAML syntax and usage guide, and a secrets.yaml security and configuration guide. Navigation is updated to register these pages, and existing documentation is refactored to link to and avoid duplicating the new concept content.

Changes

Learn the Basics Documentation Section

Layer / File(s) Summary
Foundational concept pages and navigation registry
docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md, docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md, docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md, mkdocs.yml		 Three new Markdown pages explain ESPHome fundamentals (device setup, browser/Home Assistant access), YAML syntax and ESPHome usage patterns with example configurations, and secrets.yaml storage/security model with best practices. Navigation configuration registers all three pages under a new "Learn the Basics" subsection in the ESPHome Starter Kit menu.
Integration with existing documentation flows
docs/products/ESPHome-Starter-Kit/setup/first-steps.md, docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md		 A call-to-action button on the first-steps setup page links to the new ESPHome overview page. The using-secrets tutorial removes its duplicated "what is secrets.yaml" introductory section and adds an info callout directing readers to the dedicated concept page before proceeding.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

  • ApolloAutomation/docs#778: Both PRs modify mkdocs.yml navigation for the ESPHome Starter Kit section, adding or adjusting documentation links.
  • ApolloAutomation/docs#782: Directly related; this PR refactors the using-secrets.md tutorial to remove duplication and link to new concept documentation introduced here.
  • ApolloAutomation/docs#816: Both PRs modify ESPHome Starter Kit documentation structure and navigation, including updates to first-steps.md and tutorial flows.

Poem

A rabbit hops through pages bright,
Where YAML rules and secrets hide in sight,
Three learned chapters now aligned,
A "Learn the Basics" path refined. 🐰✨

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch esk-learn-the-basics

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

This was referenced May 18, 2026
Merged
Merged
Merged
Merged
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bharvey88